Skip to main content

How do I use the when section in a pipeline as code?

Modified on Wed, 21 Jun 2023 at 02:12 PM

When working with Pipeline as Code in GitLab, the "when" section is a powerful feature that allows you to control the conditions under which a job or stage should execute. By leveraging the "when" section effectively, you can create flexible and conditional workflows tailored to your specific requirements. In this guide, we'll walk you through the steps to utilize the "when" section in your pipeline as code.

  1. Understanding the "when" Section:

The "when" section defines the conditions for job execution based on specific criteria, such as changes to files, variables, or the status of previous jobs. It allows you to specify rules that determine whether a job or stage should run, be skipped, or depend on the outcome of other jobs.

  1. Conditional Execution with Rules:

Use the "rules" keyword within the "when" section to define complex conditions for job execution. Rules are expressed as an array of expressions, where each expression consists of a condition and its corresponding action. Conditions can be based on variables, changes to files, or predefined pipeline variables like the pipeline status or branch name.

  1. Simplified Conditions with Directives:

GitLab provides convenient directives that simplify common conditions for job execution. These directives include "changes", "manual", "pipeline", and "ref". By using these directives, you can easily define conditions based on file changes, manual intervention, pipeline triggers, or specific branches.

  1. Dynamic Conditions with Expressions:

For more advanced scenarios, you can use expressions within the "rules" section to create dynamic conditions. Expressions allow you to use logical operators, comparison operators, and functions to build complex conditions that evaluate to true or false. This flexibility enables you to customize job execution based on specific criteria.

  1. Chaining Jobs with Dependencies:

By leveraging the "when" section in conjunction with the "needs" keyword, you can create dependencies between jobs. This means that a job will only execute if its required dependencies have successfully completed. This feature enables you to design sophisticated workflows and ensure proper job sequencing.

  1. Combining Conditions:

The "when" section allows you to combine multiple conditions using logical operators like "and", "or", and "not". This gives you the flexibility to define complex conditions by combining expressions and directives to meet your specific requirements.

  1. Validation and Debugging:

GitLab provides validation tools to ensure that your pipeline as code syntax is correct. Use the pipeline editor or run a pipeline locally to validate and debug your pipeline configuration, including the "when" section. This helps identify any issues and ensures that your conditions are properly set up.

  1. Best Practices:

Follow best practices when using the "when" section to maintain a clean and readable pipeline as code. Use meaningful condition names, comment your code, and organize conditions logically to enhance readability and maintainability.

By effectively utilizing the "when" section in your pipeline as code, you can create dynamic and flexible workflows tailored to your project's needs. Leverage the power of conditional execution to optimize your CI/CD pipelines and streamline your development processes.